%% getFlowHeartRate
%
% Ascertains heart rate from LVOT or ascending aorta echo images
%
%% Synatax
%
% [Flow] = getFlowHeartRate(filePathFlow, Flow, dicomImg, inputAxes, instructionText);
%
% [Flow] = getFlowHeartRate('C:\Path\To\dicom.dcm', Flow, dicomImg, inputAxes, instructionText);
%
%% Description
%
% This function attempts to ascertain heart rate information from dicom
% metadata. If it is unable to do so, the user will be prompted to manually
% input the heart rate information after being shown a picture of the image.
%
%% Arguments
%
%* filePathFlow                    - char: Path to the dicom file of
%                                          interest
%
%* Flow                            - struct: Data structure containing
%                                            information from the analysis 
%                                            of LVOT or ascending aorta flow 
%                                            data
%
%* dicomImg                        - uint8: Dicom file of interest
%
%* inputAxes                       - matlab.graphics.axis.Axes (Object): 
%                                    Axes parameters for the GUI
%
%* instructionText                 - matlab.ui.control.UIControl (Object): 
%                                    Text box parameters for the 
%
%% Returns
%
%* Flow                            - struct: Data structure containing
%                                            information from the analysis 
%                                            of LVOT or ascending aorta flow 
%                                            data, including new field Flow.HR
%                                            containing heart rate
%                                            information
%                                   
%% Function Side Effects
%
%* The Flow data structure will have an additional field Flow.HR 
%
%* A warning will be printed to console if the heart rate field is not
%  detected in the dicom metadata
%
%* A warning will be printed if the heart rate field is detected in the dicom
%  metadata but it's value is not numeric, or if the user is prompted to 
%  manually enter the heart rate value and enters a value which is not
%  numeric
%
%* A warning will be printed if the heart rate field is detected in the 
%  metadata but it has no value (empty), or if the user is prompted to manually 
%  enter the heart rate value and enters a value which is empty
%
%* A warning will be printed if the heart rate field is detected in the
%  dicom metadata but it's value is not between 20 and 200, or if the user
%  is prompted to manually enter the heart rate value and enters a value 
%  which is not between 20 and 200
%
%* A message will be printed to console if the user is going to be prompted
%  to manually enter the heart rate
%
%* An image and input dialog box will be presented if the user is prompted
%  to manually enter the heart rate
%
%% Exceptions
%
%* An exception will be thrown if Flow is not type struct
%
%* An exception will be thrown if filePathFlow is not a valid file path
%
%* An exception will be thrown if filePathFlow does not point to a dicom
%  file
%
%* An exception will be thrown if dicomImg is not type uint8
%
%% See Also
%
% dicomAnalysis
% impedanceOnlyFunc
% 

function [Flow] = getFlowHeartRate(filePathFlow, Flow, dicomImg, inputAxes, instructionText)

if isa(Flow, 'struct') == 0
    flowType = class(Flow);
    error('getFlowHeartRate:invalidFlowType', ...
          'Error: \nFlow data structure is type %s and should be type struct', flowType);
end

% Validates path points to a file
if exist(filePathFlow, 'file') ~= 2
    error('getFlowHeartRate:invalidDirectoryPath',...
          'Error: \nunable to find file matching fully qualified path %s', filePathFlow);
end

% Validates path points to a dicom file
[filePathFlowPathStr,filePathFlowNameFileName,filePathFlowExt] = fileparts(filePathFlow);

assert(strcmp('.dcm', filePathFlowExt) || strcmp('.dicom', filePathFlowExt), ...
       'getFlowHeartRate:nonDicomFile', ...
       'The file at path %s is not a dicom file (has extension %s)', filePathFlow, filePathFlowExt);
   
if isa(dicomImg, 'uint8') == 0
    dicomType = class(dicomImg);
    error('getFlowHeartRate:invalidDicomType', ...
          'Error: \nDicom image is type %s and should be type struct', dicomType);    

end

Flow = importFlowHeartRate(filePathFlow,Flow);

heartRatePresentAndValid = 0;

if isfield(Flow, 'HR') == 1
    
    heartRatePresentAndValid = validateHeartRate(Flow.HR);       
    
end
    
if heartRatePresentAndValid == 0
    
    disp('Prompting manual heart rate input');
    Flow.HR = getHeartRateManuallyGUI(dicomImg, inputAxes, instructionText);
   
end


end


